//*****************************************************************************
//
// lmicmds.h - The list of commands and return messages supported by the boot
//             loader.
//
// Copyright (c) 2006-2007 Luminary Micro, Inc.  All rights reserved.
//
// Software License Agreement
//
// Luminary Micro, Inc. (LMI) is supplying this software for use solely and
// exclusively on LMI's microcontroller products.
//
// The software is owned by LMI and/or its suppliers, and is protected under
// applicable copyright laws.  All rights are reserved.  Any use in violation
// of the foregoing restrictions may subject the user to criminal sanctions
// under applicable laws, as well as to civil liability for the breach of the
// terms and conditions of this license.
//
// THIS SOFTWARE IS PROVIDED "AS IS".  NO WARRANTIES, WHETHER EXPRESS, IMPLIED
// OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
// LMI SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR
// CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
//
// This is part of revision 323 of the Stellaris boot loader.
//
//*****************************************************************************

#ifndef __LMICMDS_H__
#define __LMICMDS_H__

//*****************************************************************************
//
//! \defgroup lmicmds Boot Loader Commands
//!
//! This section describes the list of commands that can be sent to the boot
//! loader.  The first byte of the data in a packet should always be one of the
//! commands defined here followed by data or parameters as determined
//! by the command that is sent.
//!
//! @{
//
//*****************************************************************************

//*****************************************************************************
//
//! This command is used to receive an acknowledge from the the boot loader
//! proving that communication has been established.  This command is a single
//! byte that has no parameters.
//!
//! The format of the buffer is the following:
//!
//! <code>
//! unsigned char Data[1];
//!
//! Data[0] = COMMAND_PING;
//! </code>
//!
//
//*****************************************************************************
#define COMMAND_PING            0x20

//*****************************************************************************
//
//! This command is sent to the boot loader to indicate where to store data
//! and how many bytes will be sent by the COMMAND_SEND_DATA commands that
//! follow.  The command consists of two 32-bit values that are both
//! transferred MSB first.  The first 32-bit value is the address to start
//! programming data into, while the second is the 32-bit size of the data that
//! will be sent.  This command also triggers an erasure of the full
//! application area in the flash or possibly the entire flash depending on the
//! address used. This causes the command to take longer to send the ACK/NAK
//! in response to the command.  This command should be followed by a
//! COMMAND_GET_STATUS to ensure that the program address and program size were
//! valid for the microcontroller running the boot loader.
//!
//! The format of the packet to send this command is as follows:
//!
//! <code>
//! unsigned char Command[9];
//!
//! Command[0] = COMMAND_DOWNLOAD;
//!
//! Command[1] = Program Address [31:24];
//!
//! Command[2] = Program Address [23:16];
//!
//! Command[3] = Program Address [15:8];
//!
//! Command[4] = Program Address [7:0];
//!
//! Command[5] = Program Size [31:24];
//!
//! Command[6] = Program Size [23:16];
//!
//! Command[7] = Program Size [15:8];
//!
//! Command[8] = Program Size [7:0];
//! </code>
//
//*****************************************************************************
#define COMMAND_DOWNLOAD        0x21

//*****************************************************************************
//
//! This command returns the status of the last command that was issued.
//! Typically this command should be received after every command is sent to
//! ensure that the previous command was successful or, if unsuccessful, to
//! properly respond to a failure.  The command requires one byte in the data
//! of the packet and the boot loader should respond by sending a packet with
//! one byte of data that contains the current status code.
//!
//! The format of the packet that is received is as follows:
//!
//! <code>
//! unsigned char Command[1];
//!
//! Command[0]= COMMAND_GET_STATUS;
//! </code>
//!
//! The following are the definitions for the possible status values that can
//! be returned from the boot loader when <tt>COMMAND_GET_STATUS</tt> is sent
//! to the microcontroller.
//!
//! <code>
//! \#define COMMAND_RET_SUCCESS         0x40
//!
//! \#define COMMAND_RET_UNKNOWN_CMD     0x41
//!
//! \#define COMMAND_RET_INVALID_CMD     0x42
//!
//! \#define COMMAND_RET_INVALID_ADD     0x43
//!
//! \#define COMMAND_RET_FLASH_FAIL      0x44
//! </code>
//!
//
//*****************************************************************************
#define COMMAND_GET_STATUS      0x23

//*****************************************************************************
//
//! This command should only follow a COMMAND_DOWNLOAD command or another
//! COMMAND_SEND_DATA command, if more data is needed.  Consecutive send data
//! commands automatically increment the address and continue programming from
//! the previous location.  The caller should limit transfers of data to a
//! maximum 8 bytes of packet data to allow the flash to program successfully
//! and not overflow input buffers of the serial interfaces.  The command
//! terminates programming once the number of bytes indicated by the
//! COMMAND_DOWNLOAD command has been received.  Each time this function is
//! called, it should be followed by a COMMAND_GET_STATUS command to ensure
//! that the data was successfully programmed into the flash.  If the boot
//! loader sends a NAK to this command, the boot loader will not increment the
//! current address to allow retransmission of the previous data.
//!
//! The format of the packet to send this command is as follows:
//!
//! <code>
//! unsigned char Command[9];
//!
//! Command[0] = COMMAND_SEND_DATA
//!
//! Command[1] = Data[0];
//!
//! Command[2] = Data[1];
//!
//! Command[3] = Data[2];
//!
//! Command[4] = Data[3];
//!
//! Command[5] = Data[4];
//!
//! Command[6] = Data[5];
//!
//! Command[7] = Data[6];
//!
//! Command[8] = Data[7];
//! </code>
//
//*****************************************************************************
#define COMMAND_SEND_DATA       0x24

//*****************************************************************************
//
//! This command is used to tell the boot loader to reset.  This is
//! used after downloading a new image to the microcontroller to cause the new
//! application or the new boot loader to start from a reset.  The normal boot
//! sequence occurs and the image runs as if from a hardware reset.
//! It can also be used to reset the boot loader if a critical error
//! occurs and the host device wants to restart communication with the boot
//! loader.
//!
//! The format of the command is as follows:
//!
//! <code>
//! unsigned char Command[1];
//!
//! Command[0] = COMMAND_RESET;
//! </code>
//!
//! The boot loader responds with an ACK signal to the host device before
//! actually executing the software reset on the microcontroller running the
//! boot loader.  This informs the updater application that the command was
//! received successfully and the part will be reset.
//
//*****************************************************************************
#define COMMAND_RESET           0x25

//*****************************************************************************
//
//! This is returned in response to a COMMAND_GET_STATUS command and indicates
//! that the previous command completed successful. 
//
//*****************************************************************************
#define COMMAND_RET_SUCCESS     0x40

//*****************************************************************************
//
//! This is returned in response to a COMMAND_GET_STATUS command and indicates
//! that the command sent was an unknown command.
//
//*****************************************************************************
#define COMMAND_RET_UNKNOWN_CMD 0x41

//*****************************************************************************
//
//! This is returned in response to a COMMAND_GET_STATUS command and indicates
//! that the previous command was formatted incorrectly.
//
//*****************************************************************************
#define COMMAND_RET_INVALID_CMD 0x42

//*****************************************************************************
//
//! This is returned in response to a COMMAND_GET_STATUS command and indicates
//! that the previous download command contained an invalid address value.
//
//*****************************************************************************
#define COMMAND_RET_INVALID_ADR 0x43

//*****************************************************************************
//
//! This is returned in response to a COMMAND_GET_STATUS command and indicates
//! that an attempt to program or erase the flash has failed.
//
//*****************************************************************************
#define COMMAND_RET_FLASH_FAIL  0x44

//*****************************************************************************
//
// Close the Doxygen group.
//! @}
//
//*****************************************************************************

#endif // __LMICMDS_H__
